'\" t
'
' Name:		tpinstall.1m
'
' Completed:	15th August, 2003.
'
' Updated:	6th August, 2004.
'
' Purpose:	Describes the tpinstall command.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
' 		@(#)1.2 Include information on bundle support (SE)
'
.TH tpinstall 1M "6 August 2004" "Linuxha.net"

.SH NAME
tpinstall - Install or commit packages

.SH SYNOPSYS
.TS
l l.
tpinstall -i ...	Install a specified package

tpinstall -c ...	Commit an installed package

tpinstall -P -i ...	Preview package installation
.TE

.SH DESCRIPTION

The \fitpinstall(1M)\fP utility can be used to commit or install a specified
package or one or more packages contained in a bundle, that have been
distributed either as a "Tar Package" (a.k.a. "Tarp") format, or "Tar Bundle"
(a.k.a "Tarpb").

For information on the meanings of "installed" and "committed" packages, 
please see the \fItpintro(1M)\fP manual page.

.SH INSTALLING SOFTWARE

The utility will install the specified package, bundle or components of a
bundle by extracting software from a "depot" (again see the
\fItpintro(1M)\fP manual page for details). The utility will install the
latest version available, specifically for this Operating System and
Architecture, if the specified package is not already installed at a level 
available in the given depot.

.SS Package Name Specifications

A "Tarp" package has a file extension ".tarp" (optionally 
followed by an extension to indicate the file has been compressed). Such
files contain a single package, and the name of the package can be used
to indicate this package should be installed.

The format of the file name usually something similar to the following:

.TS
l.
pkgname,1-0-0,HP-UX,9000800.tarp.gz
.TE

When attempting to install this package specify the "pkgname" as the
name of the package to install.

A "Tarpb" package file has a file extension of ".tarpb" - again optionally
followed by a compression extension. This file contains one or more "Tarp" 
packages, which may, or may not, be suitable for the current machine.

A bundle typically has a name similar to the following:

.TS
l.
fred,1-2-0.tarpb
.TE

Installation of this bundle can be performed by selecting "fred" as the
name of the software to install.

.TP 6
.B NOTE
If a directory has a package named "X" and a bundle named "X", then 
if the \fItpinstall(1M)\fP command is called with "X" the package is always
choosen rather than the bundle.
.RE

When a bundle of software is selected only the software that is suitable
to the current machine is actually installed - as per rules discussed 
later in this manual page.

It is not necessary to install all packages that a bundle contains -
an indiviudal package can be installed simply by specifying the name of
the package to install. For example if a bundle "fred" contains a package
"fileutils", then that package can be installed by specifying the
name "fred.fileutils".

Finally the installation also supports shell-type wild card matching,
meaning that to install all packages starting with the word "file" in the
"fred" bundle, the following package name to installed would be 
specified - "fred.file*".

.SS Package Installation Arguments

When installing software the following arguments are supported. Unless
otherwise stated each argument is optional.

.TP 4
.B -i
Mandatory argument that indicates that you wish to install the 
software specified.

.TP
.B -p
This is used to specify the name of the package to install. It should be
immediately followed by the full package name. This argument and value are
mandatory. It can follow the naming scheme as discussed in the
\fBPackage Name Specifications\fP section previously.
.TP
.B -d
Specify the depot from which to extract and install the software from, 
including any dependencies. 
.TP
.B -f
Force the installation of the package. This will install the latest version
meeting the criteria from the selected depot, even if that version is the
same or older than the installed version.

You are strongly discouraged from using this argument since it can lead to 
problems, especially when used on packages you know little about.

It should be noted that the force option will also affect how the
"preinstall" script - if present for a package - is interpretted. Without
the force option if this script returns a non-zero (failure) return code
then the installation of the package will be aborted. With the force
option this failure will be changed to a warning - allowing the package
installation to continue.

If a package has a "checkinstall" script present (see below for details)
then a failure for that script means that the package will not be installed
whether the force flag is set or not.

.TP
.B -v
Verbose mode - show copious progress messages to the standard output
devices. Without this you will only see warnings (to standard output) and
errors (to standard error).

Since package installation can take some time you are encouraged to make
use of this argument.
.TP
.B -r
Override the root installation directory defined in the package. If any
dependencies are also installed, this option will be passed to the
installation of those packages as well.

If this is not specified, it will default to the value of the ROOTDIR
parameter in the package, which defaults to "/".

It should be noted that in the same release database it is still only
possible to install a certain package once, even if you want to install it
to different root directories.
.TP
.B -l
List the version of the specified package from the depot that is to be
installed, and also the status of any dependencies for that package.

This is not tested to a great extent, but the theory should support
nested dependencies without problems, (though no loop detection is currently
in place).

This option is mainly used as an internal function when working out
dependencies though it can be used to query the 
.TP
.B -x
Ignore package dependencies. Normally when you install a package it will
drag in all necessary dependencies from the depot and ensure these are 
installed prior to installing the specified package.

If any of the dependencies at the required levels are not available an
error will be given and the package will not be installed. However, if this
flag is used then no dependencies will be installed, and so if any are 
missing merely a warning will be given, rather than it aborting with
an error.
.TP
.B -n
This flag is used to indicate that the specified packages should not be
automatically committed. This flag is inherited by any installation of
dependencies of this package.

When a package is not automatically commited it can still be used, but always
the overwritten files to be restored on back-out. 
.TP
.B -s
No security settings. When this flag is specified then the installation
permissions and ownerships of the files will not be changed to the values
specified as part of the package creation.

In versions prior to 1.2.2 this flag was usually necessary if a non-root
user was installing packages. As of version 1.2.2 onwards the 
permissions scripts only set the permissions and leave the owner and
group unchanged when not running as root.

.SS Choosing Which Package to Install
When you install a package you only specify the name of the package and
optionally the depot from from which it should be installed. What happens when
the depot contains more than one version of this package - which one is 
installed.

When choosing which package to install the following rules are followed,
in addition to the information shown previously:

.TP 4
[1]
If one or more versions of the package exist that specified the Operating
System and specific architecture, then any other less specific versions are
ignored from consideration.
.TP
[2] If any files exist for the specified Operating System, then any less
specific versions are ignored from consideration.
.TP
[3]
Any files with a different Operating system or architecture are excluded
from the list of files.
.RE

After applying these rules the package with the highest version number will
be installed. Thus even if you have a generic package of version "2.01.00", and
a specific version of "1.00.00", the specific version will be picked for
installation.

If this is not the behaviour you expect then the recommendation is to use
different depots for generic and specific packages.

.SS Handling Dependencies
Given the simplistic aims of the "Tarp" package format the handling of 
dependencies is similarly straightforward. It a package has dependencies that
for each dependent package a check will be made to see if the version
required is installed.

If the required version is installed then no action is taken. If an older 
version is installed, or the package not installed at all, a note is taken. 
For each of the dependencies to upgrade or install a check is made in the
depot specified to see if a suitable version exists. If it does it is added 
to a list of packages to install. If it does not an error or warning will
be generated depending on the flags used on the command line.

This process is recursive ... if any of the packages listed as dependencies
have dependencies they will also be checked and added to the list of
packages to install.

In most circumstances this approach works quite well - it will ensure that
all dependencies are installed prior to installing the package you want - or
if any of the packages are not available an error will be given before
attempting to install any packages.

This solution does suffer from three main limitations at present:

.TP 4
[1]
No provision is made for self referential dependencies. Currently on
encountering such a dependency list the installation progress will run for
ever, (or at least until it runs out of resource).
.TP
[2]
The way in which the software orders the installation of packages only works
on a list basis, rather than on a tree structure which would give better
handling of multiple products to install with the same dependencies.
.TP
[3] 
The installation is not "atomic". Consider trying to install package "A", which
has a dependency in package "B" which is not currently installed. If during the
installation package "A" fails and back-out, it will only back-out the files
installed for package "A" - package "B" will be left installed.
.TP
[4]
As of the current version handling dependencies in a bundle requires that
the dependencise are contained in the bundle itself - which is one of the
reasons the next release will contain functionality to provide scanning
of mutliple depots when looking for dependencies.
be a problem 

.RE

.SH COMMITING SOFTWARE
By default an package you request to install will be commited - there are only
two cases where this does not happen:

.TP 4
[1]
Software or system crash. If the server unexpectedly crashes before a
commit can complete, the package will be left in an "installed" or "broken"
state.

On start-up any packages in the installed state will be left installed, whilst
any packages in the broken state will be recovered and removed.
.TP
[2]
If the \fI-n\fP flag has been used on the command line when installing 
software the package will be left in "installed" state and can be manually
committed at a later date.
.RE

The difference between installed and committed status of a package is that
when \fItpremove(1M)\fP is used on an installed package, all files that
were over-written during the package installation will be restored.

.SS Package Commit Arguments

When committing software the following arguments are supported. Unless
otherwise stated each argument is optional.

.TP 4
.B -c
Mandatory argument that indicates that you wish to commit the 
software specified.
.TP
.B -p
Mandatory argument that is used to specify the name of the package to
commit. At the moment no wild cards are supported - only a single package
can be committed at a time.
.B -v
Verbose mode - show copies progress messages to the standard output
devices. Without this you will only see warnings (to standard output) and
errors (to standard error).

.SH INSTALLATION SCRIPTS
The Tarp format includes a limited ability for the package writer to 
run a script prior to installation and after installation. The return
codes of the scripts affect how the rest of the installation function.

When running either script the environment variables \fBPACKAGE\fP and
\fBVERSION\fP are set, storing the name of the package and the version 
that are being installed.

.SS Pre-installation script
This script is run before any of the software that is included in the 
package is actually installed - so don't attempt to use it!

The script should issue a return code 0 for the installation to continue.
return code 1 indicates that installation should continue, but only if the
\fB-f\fP flag has been specified to force installation. Any greater value
will always abort the installation, no matter what flags are specified. 

.SS Post-installation script
The environment variables for the post installation script are the same
as the pre-installation script. Please note that the return code will
cause the installation process to give a warning if it is not 0, but will
not cause the installation be to aborted.

.SH PACKAGE FORMATS
When a package is created it will have the extension ".tarp" - this should
be kept since this utility and the others in the family expect the tapes to
use this extension and will not recognise files with different extensions.

Of course to save bandwidth when distributing files over a network these
files are typically compressed. If you wish to compress the files then the
following compression formats are recommended:

.TP 6
* Gzip
This format is probably the most common "open" format available and is hence
the one recommended for general use. When a tarp archive is compressed in this
format the file name will be changed to have the extension ".tarp.gz".
.TP
* Bzip2
A less common format but offering better compression than Gzip. When a file
is compressed using this command the extension will be ".tarp.bz2".
.RE
.RS 6

As of version 1.1.5 of this software the commands \fitpinstall(1M)\fP and
\fitplist(1M)\fP both recognise these compressed formats and can deal with
them without requiring the user to uncompress them first. This is a small
change but significantly improves usability.

.SH EXAMPLES
The first example attempts to install the package "tools" to the default
installation directory, installing any dependencies as necessary. It takes
the depot to install from as the current directory.

.TS
l.
tpinstall -i -p tools -v
.TE

The next example installs the package "tools2", ignoring any dependencies,
from the depot "/var/packages", installing the latest version available from 
the depot - even if it is older than a version currently installed.

.TS
l.
tpinstall -i -d /var/packages -p tools2 -f -x
.TE

The final example shows the package "tools3" being committed, since it was
previously installed without being committed.

.TS
l.
tpinstall -c -p tools3 
.TE

.SH EXIT CODES
The utility makes extensive use of exit codes, you are encourgaged to check
the return code if an error occurs and refer to the following values.

.TP 4
.B 0
The specified package has been successfully installed or committed.
.TP
.B 1
Invalid command line arguments have been specified - a usage message will
have been shown on standard errror.
.TP
.B 2
The package specified to install on the command line can not be found in the 
depot. This indicates that the depot contains NO copies of the package,
even those for different Operating Systems or architectures.
.TP
.B 3
The package asked to be committed is not actually yet installed - use the
\fItplist(1M)\fP command to list the actual packages installed.
.TP
.B 4
None of the packages in the depot specified are compatible with the 
current machine.
.TP
.B 6
The package specified is not in the correct state to be committed. This is
typically because it is already committed, or "broken". A broken package is 
one that was uncleanly aborted during installation, (via a TERM signal).
.TP
.B 7
When attempting to alter the details for a package that was previously 
installed, or is now being installed the process was unable to write to the
status file for that package.
Please ensure that the file system used for the /var/adm/tarp directory 
(or the directory specified in the \fBTARP_DB\fP environment variable, if set),
has free space available.
.TP
.B 8
If you are attempting to install a different version of a package that is
already installed you must ensure that the package has first been committed. 
This return code indicates that the specified package is not committed.
.TP
.B 9
The latest version found to install from the depot is older than the
currently installed version. If you do wish to install that version then you
will need to re-run the command specifying the \fB-f\fP to force installation.
.TP
.B 10
The directory which contains the configuration of installed packages
does not exist, and an error occured whilst trying to create it. 

By default this directory is /var/adm/tarp, but it can be overridden using the
\fBTARP_DB\fP environment variable.
.TP
.B 11
A temporary directory to install the package into has been created, but
now no longer exists, or has had permissions changed so this process is unable
to use it as a working directory.
.TP
.B 12
The location of the depot on the command line has not been specified as an
absolute path. For example if the you wish to refer to the directory above
the current directory then use "$PWD/.." rather than just "..".
.TP
.B 13
An error occured whilst extracting the contents of the package to install
to a temporary directory. Please ensure that permissions and storage 
exist in the /var/adm/tarp directory to store the complete contents of the
package.

As usual this will tidy up the temporary files before exiting, leaving the
package completely un-installed state.
.TP
.B 14
The software was unable to create a directory to store the files that the
installation of this software will over-write. This facility is needed to
ensure that a clean recovery will revert the environment back to its 
original state. 

The directory used to store this information is the same as mentioned in the
previous error condition.
.TP
.B 15
Out of file system space whilst saving files that are due to be overwritten
by installation of the package. Please ensure the /var/adm/tarp directory -
or wherever \fBTARP_DB\fP points to has enough available space.
.TP
.B 16
An error occurred whilst attempting to install the files for the package. This
typically occurs due to invalid permissions or lack of disk space.
.TP
.B 17
The process was unable to write the package status information back to the 
database. Typically this will occur if the file system holding the
/var/adm/tarp directory - or wherever \fBTARP_DB\fP points to has enough 
available free space.
.TP
.B 18
Unable to temporarily move details of a previous installation of this
package to a temporary directory. Usuaully a space issue in the package
database area, as mentioned in previous errors.
.TP
.B 19
Whilst attempting to complete the update of the package status an error 
occured. This can only really occur if someone is actually installing the
same package at the same time on this host!

.TP
.B 20
A fatal error code was returned from the preinstall script for the specified
package.
.TP
.B 21
A non-fatal error code was returned from the preinstall script - however the 
\fB-f\fP was not specified so the process is aborting.
.TP
.B 23
Unable to create the temporary directory to spool the software into. This 
is a sub-directory of the software installation database - so please ensure
that adequate space is available for the directory /var/adm/tarp - or wherever
the \fBTARP_DB\fP environment variable refers to.
.TP
.B 24
Although the package had the correct naming scheme to be recognised as a
Tarp package, it was actually not the package in the expected format.
.TP
.B 25
When attempting to make a temporary directory to handle dependency information
an error occured. This is typically due to /var/adm/tarp - or wherever the
\fBTARP_DB\fP environment refers to, not having adequate storage.
.TP
.B 30
One or more dependencies that must be installed before this package can
be installed were found to be missing.

If the \fB-x\fP flag is used a warning will be issued rather than the 
install session aborting with this error condition.
.TP
.B 31
An error occured whilst installing a package on which the specified package
on the command depends. The errored package will be removed and the specified
package will obviously not be installed.
.TP
.B 32
The process was unable to write the path details of the installed root
directory of the package to the configuration database. This is typically due
to lack of storage for the /var/adm/tarp directory, or wherever the
\fBTARP_DB\fP refers to.
.TP
.B 33
Prior to removal of the temporary files in the package database area an
error occured. This might be due to the directory being removed by
another user.

.SH FILES
The following files are expected to exist in the package
database for this package once the package has been installed. The
default location for this database is /var/adm/tarpdb, though this can be
overridden using the \fBTARP_DB\fP environment variable.

.TP 12
.B spec
This file contains the package specification information, such as vendor,
license and version information.
.TP
.B status
The status of the package, whether installed, committed, or broken.
.TP
.B rootdir
The root directory that was used for installation of the package.
.TP
.B cksums
Contains the names and checksums of all the files installed as part of
the package.
.TP
.B preremove
The script to run prior to removing a package. If a return code greater than
one is returned the removal of the package will be ignored, unless the force
option is used. For more information please see the \fItpremove(1M)\fP 
manual page.
.TP
.B postremove
The script that will be called after the package has been successfully
removed from the host. See the \fItpremove(1M)\fP manual page for more
details.
.SH SEE ALSO
.BR tpintro(1M),
.BR tpremove(1M),
.BR tppkg(1M),
.BR tplist(1M),
.BR tpchk(1M).

.SH NOTES
Please carefully read the following notes also before using them command,
since they contain important information.

.TP 4
[1]
During the installation process the complete contents of the package 
currently being installed will be extracted to a temporary directory
below the Installed Package database, (either "/var/adm/tarpdb" or the
directory defined by the \fBTARP_DB\fP environment variable).

In the same temporary directory it stores any files it is currently
over-writing is well -  which might be significant if a previous
version of the package is already installed.


Thus it is important that wherever the installed package database exists
.SH WARRANTY/LICENSE/ENVIRONMENT
This utility is available under the GNU GPL, and comes with 
\fIno warranty or guarantee of any kind\fP.

This program is only suitable for environments that have the following
software components installed:

.TP 4
.B Shell Utilities
The following utilities are required, \fIawk(1)\fP, \fIksh(1)\fP
as well as the standard utiltiies to check, move and remove files and 
directories.
.TP
.B Perl
Any version of Perl from 4 onwards with standard installation libraries
should be suitable. Currently Perl is only used spareingly, but still must
be available.

